<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>The PyPOISE module &mdash; pysam 1.0 documentation</title>
    
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '1.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="pysam 1.0 documentation" href="index.html" />
    <link rel="prev" title="Introduction" href="intro.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="intro.html" title="Introduction"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">pysam 1.0 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="module-pypoise">
<span id="the-pypoise-module"></span><h1>The PyPOISE module<a class="headerlink" href="#module-pypoise" title="Permalink to this headline">¶</a></h1>
<p>The main module to implement the Phase Observationally Independent of
Systematic Errors (POISE) algorithm.</p>
<dl class="function">
<dt id="pypoise.extract_kerphase">
<tt class="descclassname">pypoise.</tt><tt class="descname">extract_kerphase</tt><big>(</big><em>ptok_file='', ftpix=([], []), ptok=[], cube=[], cube_file='', add_noise=0, rnoise=10.0, gain=4.0, out_file='', recompute_ptok=False, use_poise=False, systematic=[], cal_kp=[], summary_file='', pas=[0], ptok_out='', window_edges=True</em><big>)</big><a class="headerlink" href="#pypoise.extract_kerphase" title="Permalink to this definition">¶</a></dt>
<dd><p>Extract the kernel-phases.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>cube: (Nframes,Nx,Ny) array (dtype=float)</strong></p>
<blockquote>
<div><p>The cleaned input data</p>
</div></blockquote>
<p><strong>ftpix: (K array,K array)</strong></p>
<blockquote>
<div><p>The Fourier pixel sampling points, from pupil_sampling</p>
</div></blockquote>
<p><strong>ptok: (M,K) array</strong></p>
<blockquote>
<div><p>The phase to kernel-phase matrix, from pupil_sampling</p>
</div></blockquote>
<p><strong>add_noise: int</strong></p>
<blockquote>
<div><p>Multiplier for the number of frames to add fake noise to. 0 turns
this feature off.</p>
</div></blockquote>
<p><strong>rnoise: float</strong></p>
<blockquote>
<div><p>Readout noise in DN</p>
</div></blockquote>
<p><strong>gain: float</strong></p>
<blockquote>
<div><p>Gain in electrons/DN. Photon variance in DN is N/gain</p>
</div></blockquote>
<p><strong>out_file: string, optional</strong></p>
<blockquote>
<div><p>File to save the kernel-phases to.</p>
</div></blockquote>
<p><strong>cube_file: string, optional</strong></p>
<blockquote>
<div><p>Optional file input.</p>
</div></blockquote>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">kp: (Nframes*extra_noisy_frames,M)</p>
<blockquote class="last">
<div><p>Kernel phase array.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="pypoise.implane_fit_binary">
<tt class="descclassname">pypoise.</tt><tt class="descname">implane_fit_binary</tt><big>(</big><em>kp_implane_file</em>, <em>summary_file=''</em>, <em>out_file=''</em>, <em>pa_vertical=0</em>, <em>to_sky_pa=False</em><big>)</big><a class="headerlink" href="#pypoise.implane_fit_binary" title="Permalink to this definition">¶</a></dt>
<dd><p>A binary grid search to a kp_implane file.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>kp_implane_file: string</strong></p>
<blockquote>
<div><p>The fits file containing the kernel-phase to implane data
(and, optionally, the data also)</p>
</div></blockquote>
<p><strong>summary_file: string</strong></p>
<blockquote>
<div><p>The kernel-phase results file.</p>
</div></blockquote>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">p, crat, crat_sig, chi2</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="pypoise.kp_binary_fit">
<tt class="descclassname">pypoise.</tt><tt class="descname">kp_binary_fit</tt><big>(</big><em>summary_files</em>, <em>initp</em><big>)</big><a class="headerlink" href="#pypoise.kp_binary_fit" title="Permalink to this definition">¶</a></dt>
<dd><p>Fit a binary model to kernel-phases</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>summary_files: string array</strong></p>
<blockquote>
<div><p>List of input summary files.</p>
</div></blockquote>
<p><strong>initp: (sep in mas, pa, contrast sec/primary)</strong></p>
<blockquote>
<div><p>Initial fit parameters. These can be obtained from e.g. implane_fit_binary</p>
</div></blockquote>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">(p_fit, p_sig, p_cov)</p>
<p>p_fit: [float,float,float]</p>
<p>p_sig: [float,float,float]</p>
<p>p_cov: (3,3) array</p>
<blockquote class="last">
<div><p>Best fit (sep, pa, contrast) parameters, standard deviation and 
covariance.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="pypoise.kp_binary_fitfunc">
<tt class="descclassname">pypoise.</tt><tt class="descname">kp_binary_fitfunc</tt><big>(</big><em>p</em>, <em>rad_pixels</em>, <em>subarrs</em>, <em>ftpixs</em>, <em>ptoks</em>, <em>kp_mns</em>, <em>kp_sigs</em>, <em>pas</em>, <em>ptok_files</em><big>)</big><a class="headerlink" href="#pypoise.kp_binary_fitfunc" title="Permalink to this definition">¶</a></dt>
<dd><p>This function finds the fit residuals based on input model parameters in
on-sky coorindates as (sep,PA,contrast). It can have multiple input files.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>p: [sep in mas, sky position angle in degrees, contrast secondary/primary]</strong></p>
<p><strong>rad_pixels: float list</strong></p>
<blockquote>
<div><p>Radians per pixel in the original image.</p>
</div></blockquote>
<p><strong>subarrs: float list</strong></p>
<blockquote>
<div><p>Subarray size in the original image and ftpix definition.</p>
</div></blockquote>
<p><strong>ftpixs: ( (N) array, (N) array ) list</strong></p>
<blockquote>
<div><p>Sampling points in the Fourier domain</p>
</div></blockquote>
<p><strong>ptoks:</strong></p>
<blockquote>
<div><p>Pupil to kernel-phase matrices</p>
</div></blockquote>
<p><strong>kp_mns:</strong></p>
<blockquote>
<div><p>Kernel-phases from the data</p>
</div></blockquote>
<p><strong>kp_sigs:</strong></p>
<blockquote class="last">
<div><p>Uncertainties in kernel-phases</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="pypoise.kp_binary_fitfunc_onefile">
<tt class="descclassname">pypoise.</tt><tt class="descname">kp_binary_fitfunc_onefile</tt><big>(</big><em>p</em>, <em>rad_pixel</em>, <em>subarr</em>, <em>ftpix</em>, <em>ptok</em>, <em>kp_mn</em>, <em>kp_sig</em><big>)</big><a class="headerlink" href="#pypoise.kp_binary_fitfunc_onefile" title="Permalink to this definition">¶</a></dt>
<dd><p>This function finds the fit residuals based on input model parameters in
chip-coorindates as (sep,PA,contrast).</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>p: [sep in mas, chip position angle in degrees, contrast secondary/primary]</strong></p>
<p><strong>rad_pixel: float</strong></p>
<blockquote>
<div><p>Radians per pixel in the original image.</p>
</div></blockquote>
<p><strong>subarr: float</strong></p>
<blockquote>
<div><p>Subarray size in the original image and ftpix definition.</p>
</div></blockquote>
<p><strong>ftpix: ( (N) array, (N) array )</strong></p>
<blockquote>
<div><p>Sampling points in the Fourier domain</p>
</div></blockquote>
<p><strong>ptok:</strong></p>
<blockquote>
<div><p>Pupil to kernel-phase matrix</p>
</div></blockquote>
<p><strong>kp_mn:</strong></p>
<blockquote>
<div><p>Kernel-phases from the data</p>
</div></blockquote>
<p><strong>kp_sig:</strong></p>
<blockquote class="last">
<div><p>Uncertainties in kernel-phases</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="pypoise.kp_to_implane">
<tt class="descclassname">pypoise.</tt><tt class="descname">kp_to_implane</tt><big>(</big><em>ptok_file=[], pas=[0], summary_files=[], pxscale=10.0, sz=128, out_file=''</em><big>)</big><a class="headerlink" href="#pypoise.kp_to_implane" title="Permalink to this definition">¶</a></dt>
<dd><p>Here we convert kernel-phases to their image-plane representation,
in sky coordinates.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>ptok_file: string</strong></p>
<blockquote>
<div><p>The input fits file containing the ptok matrix</p>
</div></blockquote>
<p><strong>pas: float, optional</strong></p>
<blockquote>
<div><p>The position angles of vertical</p>
</div></blockquote>
<p><strong>summary_files: string array, optional</strong></p>
<blockquote>
<div><p>The list of filenames to get position angles and summary data from</p>
</div></blockquote>
<p><strong>pxscale: float</strong></p>
<blockquote class="last">
<div><p>Output pixel scale in arcsec per pixel</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="pypoise.mod2pi">
<tt class="descclassname">pypoise.</tt><tt class="descname">mod2pi</tt><big>(</big><em>angle</em><big>)</big><a class="headerlink" href="#pypoise.mod2pi" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert an angle to the range (-pi,pi)</p>
</dd></dl>

<dl class="function">
<dt id="pypoise.pmask_to_ft">
<tt class="descclassname">pypoise.</tt><tt class="descname">pmask_to_ft</tt><big>(</big><em>pmask</em><big>)</big><a class="headerlink" href="#pypoise.pmask_to_ft" title="Permalink to this definition">¶</a></dt>
<dd><p>Create Fourier sampling for kerphase based on a pupil mask.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>pmask: (subarr, subarr) array</strong></p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">RR: (subarr,subarr) array</p>
<blockquote>
<div><p>Two-dimensional redundancy array, computing how many baselines
contribute to each Fourier pixel.</p>
</div></blockquote>
<p>AA: (subarr,subarr,npsi) array</p>
<blockquote>
<div><p>A two-dimensional array for each pupil position, showing how phase
at that position contributes to the particular Fourier component phase
(+1 or -1)</p>
</div></blockquote>
<p>ftpix: ( (nphi) array, (nphi) array)</p>
<blockquote class="last">
<div><p>Co-ordinates defining the Fourier sampling.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="pypoise.poise_kerphase">
<tt class="descclassname">pypoise.</tt><tt class="descname">poise_kerphase</tt><big>(</big><em>kp_files</em>, <em>ptok=</em>, <span class="optional">[</span><span class="optional">]</span><em>ftpix=(</em>, <span class="optional">[</span><span class="optional">]</span><span class="optional">[</span><span class="optional">]</span><em>)</em>, <em>fmask=</em>, <span class="optional">[</span><span class="optional">]</span><em>beta=0.4</em>, <em>out_file=''</em>, <em>rad_pixel=0.0</em>, <em>subarr=128</em><big>)</big><a class="headerlink" href="#pypoise.poise_kerphase" title="Permalink to this definition">¶</a></dt>
<dd><p>Extract the POISE kernel-phases, returning a new ptok matrix</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>kp_files: list of strings</strong></p>
<blockquote>
<div><p>List of kp filenames to turn in to kernel phases.</p>
</div></blockquote>
<p><strong>ptok: (K,M) array</strong></p>
<blockquote>
<div><p>The phase to kernel-phase array.</p>
</div></blockquote>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">ptok_poise: (K_new,M) array</p>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Notes</p>
<p>This works on files rather than all the data, because it could take up
too much memory. As bad files can&#8217;t be rejected until kernel-phases are
computed, saving kp files is the only way to only compute them once.</p>
</dd></dl>

<dl class="function">
<dt id="pypoise.pupil_sampling">
<tt class="descclassname">pypoise.</tt><tt class="descname">pupil_sampling</tt><big>(</big><em>in_files</em>, <em>subarr=128</em>, <em>ignore_data=False</em>, <em>dark_file=''</em>, <em>flat_file=''</em>, <em>out_file=''</em>, <em>rdir=''</em><big>)</big><a class="headerlink" href="#pypoise.pupil_sampling" title="Permalink to this definition">¶</a></dt>
<dd><p>Define the Fourier-Plane sampling based on Pupil geometry</p>
<p>This function finds the pupil sampling and the matrix that maps phase to 
closure-quantities, i.e. kernel-phases.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>h</strong> : A fits header dictionary-like structure returned from pyfits or</p>
<blockquote>
<div><p>astropy.io.fits. Must be from a known camera in a known mode.</p>
</div></blockquote>
<p><strong>subarr</strong> : int</p>
<blockquote>
<div><p>The sub-array size</p>
</div></blockquote>
<p><strong>ignore_data</strong> : bool</p>
<blockquote>
<div><p>Whether to ignore the data in finding the precise Fourier sampling.</p>
</div></blockquote>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">ftpix: ( (N) array, (N) array)</p>
<p>fmask: (subarr,subarr) array</p>
<p>ptok: (M,N) array</p>
<blockquote class="last">
<div><p>A matrix that maps pupil-phases to kernel-phases.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="intro.html"
                        title="previous chapter">Introduction</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/pypoise.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="intro.html" title="Introduction"
             >previous</a> |</li>
        <li><a href="index.html">pysam 1.0 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2014, Mike Ireland.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.1.
    </div>
  </body>
</html>